home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / os2 / octa209b.zip / octave-2.09 / doc / octave.i06 (.txt) < prev    next >
GNU Info File  |  1997-08-20  |  51KB  |  992 lines
  1. This is Info file octave, produced by Makeinfo-1.64 from the input file
  2. octave.tex.
  3. START-INFO-DIR-ENTRY
  4. * Octave: (octave).     Interactive language for numerical computations.
  5. END-INFO-DIR-ENTRY
  6.    Copyright (C) 1996, 1997 John W. Eaton.
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided that
  12. the entire resulting derived work is distributed under the terms of a
  13. permission notice identical to this one.
  14.    Permission is granted to copy and distribute translations of this
  15. manual into another language, under the above conditions for modified
  16. versions.
  17. File: octave,  Node: Integer Conversions,  Next: Floating-Point Conversions,  Prev: Table of Output Conversions,  Up: C-Style I/O Functions
  18. Integer Conversions
  19. -------------------
  20.    This section describes the options for the `%d', `%i', `%o', `%u',
  21. `%x', and `%X' conversion specifications.  These conversions print
  22. integers in various formats.
  23.    The `%d' and `%i' conversion specifications both print an numeric
  24. argument as a signed decimal number; while `%o', `%u', and `%x' print
  25. the argument as an unsigned octal, decimal, or hexadecimal number
  26. (respectively).  The `%X' conversion specification is just like `%x'
  27. except that it uses the characters `ABCDEF' as digits instead of
  28. `abcdef'.
  29.    The following flags are meaningful:
  30.      Left-justify the result in the field (instead of the normal
  31.      right-justification).
  32.      For the signed `%d' and `%i' conversions, print a plus sign if the
  33.      value is positive.
  34.      For the signed `%d' and `%i' conversions, if the result doesn't
  35.      start with a plus or minus sign, prefix it with a space character
  36.      instead.  Since the `+' flag ensures that the result includes a
  37.      sign, this flag is ignored if you supply both of them.
  38.      For the `%o' conversion, this forces the leading digit to be `0',
  39.      as if by increasing the precision.  For `%x' or `%X', this
  40.      prefixes a leading `0x' or `0X' (respectively) to the result.
  41.      This doesn't do anything useful for the `%d', `%i', or `%u'
  42.      conversions.
  43.      Pad the field with zeros instead of spaces.  The zeros are placed
  44.      after any indication of sign or base.  This flag is ignored if the
  45.      `-' flag is also specified, or if a precision is specified.
  46.    If a precision is supplied, it specifies the minimum number of
  47. digits to appear; leading zeros are produced if necessary.  If you
  48. don't specify a precision, the number is printed with as many digits as
  49. it needs.  If you convert a value of zero with an explicit precision of
  50. zero, then no characters at all are produced.
  51. File: octave,  Node: Floating-Point Conversions,  Next: Other Output Conversions,  Prev: Integer Conversions,  Up: C-Style I/O Functions
  52. Floating-Point Conversions
  53. --------------------------
  54.    This section discusses the conversion specifications for
  55. floating-point numbers: the `%f', `%e', `%E', `%g', and `%G'
  56. conversions.
  57.    The `%f' conversion prints its argument in fixed-point notation,
  58. producing output of the form [`-']DDD`.'DDD, where the number of digits
  59. following the decimal point is controlled by the precision you specify.
  60.    The `%e' conversion prints its argument in exponential notation,
  61. producing output of the form [`-']D`.'DDD`e'[`+'|`-']DD.  Again, the
  62. number of digits following the decimal point is controlled by the
  63. precision.  The exponent always contains at least two digits.  The `%E'
  64. conversion is similar but the exponent is marked with the letter `E'
  65. instead of `e'.
  66.    The `%g' and `%G' conversions print the argument in the style of
  67. `%e' or `%E' (respectively) if the exponent would be less than -4 or
  68. greater than or equal to the precision; otherwise they use the `%f'
  69. style.  Trailing zeros are removed from the fractional portion of the
  70. result and a decimal-point character appears only if it is followed by
  71. a digit.
  72.    The following flags can be used to modify the behavior:
  73.      Left-justify the result in the field.  Normally the result is
  74.      right-justified.
  75.      Always include a plus or minus sign in the result.
  76.      If the result doesn't start with a plus or minus sign, prefix it
  77.      with a space instead.  Since the `+' flag ensures that the result
  78.      includes a sign, this flag is ignored if you supply both of them.
  79.      Specifies that the result should always include a decimal point,
  80.      even if no digits follow it.  For the `%g' and `%G' conversions,
  81.      this also forces trailing zeros after the decimal point to be left
  82.      in place where they would otherwise be removed.
  83.      Pad the field with zeros instead of spaces; the zeros are placed
  84.      after any sign.  This flag is ignored if the `-' flag is also
  85.      specified.
  86.    The precision specifies how many digits follow the decimal-point
  87. character for the `%f', `%e', and `%E' conversions.  For these
  88. conversions, the default precision is `6'.  If the precision is
  89. explicitly `0', this suppresses the decimal point character entirely.
  90. For the `%g' and `%G' conversions, the precision specifies how many
  91. significant digits to print.  Significant digits are the first digit
  92. before the decimal point, and all the digits after it.  If the
  93. precision is `0' or not specified for `%g' or `%G', it is treated like
  94. a value of `1'.  If the value being printed cannot be expressed
  95. precisely in the specified number of digits, the value is rounded to
  96. the nearest number that fits.
  97. File: octave,  Node: Other Output Conversions,  Next: Formatted Input,  Prev: Floating-Point Conversions,  Up: C-Style I/O Functions
  98. Other Output Conversions
  99. ------------------------
  100.    This section describes miscellaneous conversions for `printf'.
  101.    The `%c' conversion prints a single character.  The `-' flag can be
  102. used to specify left-justification in the field, but no other flags are
  103. defined, and no precision or type modifier can be given.  For example:
  104.      printf ("%c%c%c%c%c", "h", "e", "l", "l", "o");
  105. prints `hello'.
  106.    The `%s' conversion prints a string.  The corresponding argument
  107. must be a string.  A precision can be specified to indicate the maximum
  108. number of characters to write; otherwise characters in the string up to
  109. but not including the terminating null character are written to the
  110. output stream.  The `-' flag can be used to specify left-justification
  111. in the field, but no other flags or type modifiers are defined for this
  112. conversion.  For example:
  113.      printf ("%3s%-6s", "no", "where");
  114. prints ` nowhere ' (note the leading and trailing spaces).
  115. File: octave,  Node: Formatted Input,  Next: Input Conversion Syntax,  Prev: Other Output Conversions,  Up: C-Style I/O Functions
  116. Formatted Input
  117. ---------------
  118.    Octave provides the `scanf', `fscanf', and `sscanf' functions to
  119. read formatted input.  There are two forms of each of these functions.
  120. One can be used to extract vectors of data from a file, and the other
  121. is more `C-like'.
  122.  - Built-in Function: [VAL, COUNT] = fscanf (FID, TEMPLATE, SIZE)
  123.  - Built-in Function: [V1, V2, ...] =  fscanf (FID, TEMPLATE, "C")
  124.      In the first form, read from FID according to TEMPLATE, returning
  125.      the result in the matrix VAL.
  126.      The optional argument SIZE specifies the amount of data to read
  127.      and may be one of
  128.     `Inf'
  129.           Read as much as possible, returning a column vector.
  130.     `NR'
  131.     `[NR, Inf]'
  132.           Read as much as possible, returning a matrix with NR rows.
  133.           If the number of elements read is not an exact multiple of
  134.           NR, the last column is padded with zeros.
  135.     `[NR, NC]'
  136.           Read up to `NR * NC' elements, returning a matrix with NR
  137.           rows.  If the number of elements read is not an exact multiple
  138.           of NR, the last column is padded with zeros.
  139.      If SIZE is omitted, a value of `Inf' is assumed.
  140.      A string is returned if TEMPLATE specifies only character
  141.      conversions.
  142.      The number of items successfully read is returned in COUNT.
  143.      In the second form, read from FID according to TEMPLATE, with each
  144.      conversion specifier in TEMPLATE corresponding to a single scalar
  145.      return value.  This form is more `C-like', and also compatible
  146.      with previous versions of Octave.
  147.  - Built-in Function: [VAL, COUNT] = sscanf (STRING, TEMPLATE, SIZE)
  148.  - Built-in Function: [V1, V2, ...] =  sscanf (STRING, TEMPLATE, "C")
  149.      This is like `fscanf', except that the characters are taken from
  150.      the string STRING instead of from a stream.  Reaching the end of
  151.      the string is treated as an end-of-file condition.
  152.  - Built-in Function: [VAL, COUNT] = scanf (TEMPLATE, SIZE)
  153.  - Built-in Function: [V1, V2, ...] =  scanf (TEMPLATE, "C")
  154.      This is equivalent to calling `fscanf' with FID = `stdin'.
  155.      It is currently not useful to call `scanf' in interactive programs.
  156.    Calls to `scanf' are superficially similar to calls to `printf' in
  157. that arbitrary arguments are read under the control of a template
  158. string.  While the syntax of the conversion specifications in the
  159. template is very similar to that for `printf', the interpretation of
  160. the template is oriented more towards free-format input and simple
  161. pattern matching, rather than fixed-field formatting.  For example,
  162. most `scanf' conversions skip over any amount of "white space"
  163. (including spaces, tabs, and newlines) in the input file, and there is
  164. no concept of precision for the numeric input conversions as there is
  165. for the corresponding output conversions.  Ordinarily, non-whitespace
  166. characters in the template are expected to match characters in the
  167. input stream exactly.
  168.    When a "matching failure" occurs, `scanf' returns immediately,
  169. leaving the first non-matching character as the next character to be
  170. read from the stream, and `scanf' returns all the items that were
  171. successfully converted.
  172.    The formatted input functions are not used as frequently as the
  173. formatted output functions.  Partly, this is because it takes some care
  174. to use them properly.  Another reason is that it is difficult to recover
  175. from a matching error.
  176. File: octave,  Node: Input Conversion Syntax,  Next: Table of Input Conversions,  Prev: Formatted Input,  Up: C-Style I/O Functions
  177. Input Conversion Syntax
  178. -----------------------
  179.    A `scanf' template string is a string that contains ordinary
  180. multibyte characters interspersed with conversion specifications that
  181. start with `%'.
  182.    Any whitespace character in the template causes any number of
  183. whitespace characters in the input stream to be read and discarded.
  184. The whitespace characters that are matched need not be exactly the same
  185. whitespace characters that appear in the template string.  For example,
  186. write ` , ' in the template to recognize a comma with optional
  187. whitespace before and after.
  188.    Other characters in the template string that are not part of
  189. conversion specifications must match characters in the input stream
  190. exactly; if this is not the case, a matching failure occurs.
  191.    The conversion specifications in a `scanf' template string have the
  192. general form:
  193.      % FLAGS WIDTH TYPE CONVERSION
  194.    In more detail, an input conversion specification consists of an
  195. initial `%' character followed in sequence by:
  196.    * An optional "flag character" `*', which says to ignore the text
  197.      read for this specification.  When `scanf' finds a conversion
  198.      specification that uses this flag, it reads input as directed by
  199.      the rest of the conversion specification, but it discards this
  200.      input, does not use a pointer argument, and does not increment the
  201.      count of successful assignments.
  202.    * An optional decimal integer that specifies the "maximum field
  203.      width".  Reading of characters from the input stream stops either
  204.      when this maximum is reached or when a non-matching character is
  205.      found, whichever happens first.  Most conversions discard initial
  206.      whitespace characters (those that don't are explicitly
  207.      documented), and these discarded characters don't count towards
  208.      the maximum field width.
  209.    * An optional type modifier character.  This character is ignored by
  210.      Octave's `scanf' function, but is recognized to provide
  211.      compatibility with the C language `scanf'.
  212.    * A character that specifies the conversion to be applied.
  213.    The exact options that are permitted and how they are interpreted
  214. vary between the different conversion specifiers.  See the descriptions
  215. of the individual conversions for information about the particular
  216. options that they allow.
  217. File: octave,  Node: Table of Input Conversions,  Next: Numeric Input Conversions,  Prev: Input Conversion Syntax,  Up: C-Style I/O Functions
  218. Table of Input Conversions
  219. --------------------------
  220.    Here is a table that summarizes the various conversion
  221. specifications:
  222.      Matches an optionally signed integer written in decimal.  *Note
  223.      Numeric Input Conversions::.
  224.      Matches an optionally signed integer in any of the formats that
  225.      the C language defines for specifying an integer constant.  *Note
  226.      Numeric Input Conversions::.
  227.      Matches an unsigned integer written in octal radix.  *Note Numeric
  228.      Input Conversions::.
  229.      Matches an unsigned integer written in decimal radix.  *Note
  230.      Numeric Input Conversions::.
  231. `%x', `%X'
  232.      Matches an unsigned integer written in hexadecimal radix.  *Note
  233.      Numeric Input Conversions::.
  234. `%e', `%f', `%g', `%E', `%G'
  235.      Matches an optionally signed floating-point number.  *Note Numeric
  236.      Input Conversions::.
  237.      Matches a string containing only non-whitespace characters.  *Note
  238.      String Input Conversions::.
  239.      Matches a string of one or more characters; the number of
  240.      characters read is controlled by the maximum field width given for
  241.      the conversion.  *Note String Input Conversions::.
  242.      This matches a literal `%' character in the input stream.  No
  243.      corresponding argument is used.
  244.    If the syntax of a conversion specification is invalid, the behavior
  245. is undefined.  If there aren't enough function arguments provided to
  246. supply addresses for all the conversion specifications in the template
  247. strings that perform assignments, or if the arguments are not of the
  248. correct types, the behavior is also undefined.  On the other hand, extra
  249. arguments are simply ignored.
  250. File: octave,  Node: Numeric Input Conversions,  Next: String Input Conversions,  Prev: Table of Input Conversions,  Up: C-Style I/O Functions
  251. Numeric Input Conversions
  252. -------------------------
  253.    This section describes the `scanf' conversions for reading numeric
  254. values.
  255.    The `%d' conversion matches an optionally signed integer in decimal
  256. radix.
  257.    The `%i' conversion matches an optionally signed integer in any of
  258. the formats that the C language defines for specifying an integer
  259. constant.
  260.    For example, any of the strings `10', `0xa', or `012' could be read
  261. in as integers under the `%i' conversion.  Each of these specifies a
  262. number with decimal value `10'.
  263.    The `%o', `%u', and `%x' conversions match unsigned integers in
  264. octal, decimal, and hexadecimal radices, respectively.
  265.    The `%X' conversion is identical to the `%x' conversion.  They both
  266. permit either uppercase or lowercase letters to be used as digits.
  267.    Unlike the C language `scanf', Octave ignores the `h', `l', and `L'
  268. modifiers.
  269. File: octave,  Node: String Input Conversions,  Next: Binary I/O,  Prev: Numeric Input Conversions,  Up: C-Style I/O Functions
  270. String Input Conversions
  271. ------------------------
  272.    This section describes the `scanf' input conversions for reading
  273. string and character values: `%s' and `%c'.
  274.    The `%c' conversion is the simplest: it matches a fixed number of
  275. characters, always.  The maximum field with says how many characters to
  276. read; if you don't specify the maximum, the default is 1.  This
  277. conversion does not skip over initial whitespace characters.  It reads
  278. precisely the next N characters, and fails if it cannot get that many.
  279.    The `%s' conversion matches a string of non-whitespace characters.
  280. It skips and discards initial whitespace, but stops when it encounters
  281. more whitespace after having read something.
  282.    For example, reading the input:
  283.       hello, world
  284. with the conversion `%10c' produces `" hello, wo"', but reading the
  285. same input with the conversion `%10s' produces `"hello,"'.
  286. File: octave,  Node: Binary I/O,  Next: Temporary Files,  Prev: String Input Conversions,  Up: C-Style I/O Functions
  287. Binary I/O
  288. ----------
  289.    Octave can read and write binary data using the functions `fread'
  290. and `fwrite', which are patterned after the standard C functions with
  291. the same names.  The are able to automatically swap the byte order of
  292. integer data and convert among ths supported floating point formats as
  293. the data are read.
  294.  - Built-in Function: [VAL, COUNT] = fread (FID, SIZE, PRECISION, SKIP,
  295.           ARCH)
  296.      Read binary data of type PRECISION from the specified file ID FID.
  297.      The optional argument SIZE specifies the amount of data to read
  298.      and may be one of
  299.     `Inf'
  300.           Read as much as possible, returning a column vector.
  301.     `NR'
  302.     `[NR, Inf]'
  303.           Read as much as possible, returning a matrix with NR rows.
  304.           If the number of elements read is not an exact multiple of
  305.           NR, the last column is padded with zeros.
  306.     `[NR, NC]'
  307.           Read up to `NR * NC' elements, returning a matrix with NR
  308.           rows.  If the number of elements read is not an exact multiple
  309.           of NR, the last column is padded with zeros.
  310.      If SIZE is omitted, a value of `Inf' is assumed.
  311.      The optional argument PRECISION is a string specifying the type of
  312.      data to read and may be one of
  313.     `"char"'
  314.     `"char*1"'
  315.     `"integer*1"'
  316.     `"int8"'
  317.           Single character.
  318.     `"signed char"'
  319.     `"schar"'
  320.           Signed character.
  321.     `"unsigned char"'
  322.     `"uchar"'
  323.           Unsigned character.
  324.     `"short"'
  325.           Short integer.
  326.     `"unsigned short"'
  327.     `"ushort"'
  328.           Unsigned short integer.
  329.     `"int"'
  330.           Integer.
  331.     `"unsigned int"'
  332.     `"uint"'
  333.           Unsigned integer.
  334.     `"long"'
  335.           Long integer.
  336.     `"unsigned long"'
  337.     `"ulong"'
  338.           Unsigned long integer.
  339.     `"float"'
  340.     `"float32"'
  341.     `"real*4"'
  342.           Single precision float.
  343.     `"double"'
  344.     `"float64"'
  345.     `"real*8"'
  346.           Double precision float.
  347.     `"integer*2"'
  348.     `"int16"'
  349.           Two byte integer.
  350.     `"integer*4"'
  351.     `"int32"'
  352.           Four byte integer.
  353.      The default precision is `"uchar"'.
  354.      The optional argument SKIP specifies the number of bytes to skip
  355.      before each element is read.  If it is not specified, a value of 0
  356.      is assumed.
  357.      The optional argument ARCH is a string specifying the data format
  358.      for the file.  Valid values are
  359.     `"native"'
  360.           The format of the current machine.
  361.     `"ieee-le"'
  362.           IEEE big endian.
  363.     `"ieee-be"'
  364.           IEEE little endian.
  365.     `"vaxd"'
  366.           VAX D floating format.
  367.     `"vaxg"'
  368.           VAX G floating format.
  369.     `"cray"'
  370.           Cray floating format.
  371.      Conversions are currently only supported for `"ieee-be"' and
  372.      `"ieee-le"' formats.
  373.      The data read from the file is returned in VAL, and the number of
  374.      values read is returned in `count'
  375.  - Built-in Function: COUNT = fwrite (FID, DATA, PRECISION, SKIP, ARCH)
  376.      Write data in binary form of type PRECISION to the specified file
  377.      ID FID, returning the number of values successfully written to the
  378.      file.
  379.      The argument DATA is a matrix of values that are to be written to
  380.      the file.  The values are extracted in column-major order.
  381.      The remaining arguments PRECISION, SKIP, and ARCH are optional,
  382.      and are interpreted as described for `fread'.
  383.      The behavior of `fwrite' is undefined if the values in DATA are
  384.      too large to fit in the specified precision.
  385. File: octave,  Node: Temporary Files,  Next: EOF and Errors,  Prev: Binary I/O,  Up: C-Style I/O Functions
  386. Temporary Files
  387. ---------------
  388.  - Built-in Function:  tmpnam ()
  389.      Return a unique temporary file name as a string.
  390.      Since the named file is not opened, by `tmpnam', it is possible
  391.      (though relatively unlikely) that it will not be available by the
  392.      time your program attempts to open it.
  393. File: octave,  Node: EOF and Errors,  Next: File Positioning,  Prev: Temporary Files,  Up: C-Style I/O Functions
  394. End of File and Errors
  395. ----------------------
  396.  - Built-in Function:  feof (FID)
  397.      Return 1 if an end-of-file condition has been encountered for a
  398.      given file and 0 otherwise.  Note that it will only return 1 if
  399.      the end of the file has already been encountered, not if the next
  400.      read operation will result in an end-of-file condition.
  401.  - Built-in Function:  ferror (FID)
  402.      Return 1 if an error condition has been encountered for a given
  403.      file and 0 otherwise.  Note that it will only return 1 if an error
  404.      has already been encountered, not if the next operation will
  405.      result in an error condition.
  406.  - Built-in Function:  freport ()
  407.      Print a list of which files have been opened, and whether they are
  408.      open for reading, writing, or both.  For example,
  409.           freport ()
  410.           
  411.                -|  number  mode  name
  412.                -|
  413.                -|       0     r  stdin
  414.                -|       1     w  stdout
  415.                -|       2     w  stderr
  416.                -|       3     r  myfile
  417. File: octave,  Node: File Positioning,  Prev: EOF and Errors,  Up: C-Style I/O Functions
  418. File Positioning
  419. ----------------
  420.    Three functions are available for setting and determining the
  421. position of the file pointer for a given file.
  422.  - Built-in Function:  ftell (FID)
  423.      Return the position of the file pointer as the number of characters
  424.      from the beginning of the file FID.
  425.  - Built-in Function:  fseek (FID, OFFSET, ORIGIN)
  426.      Set the file pointer to any location within the file FID.  The
  427.      pointer is positioned OFFSET characters from the ORIGIN, which may
  428.      be one of the predefined variables `SEEK_CUR' (current position),
  429.      `SEEK_SET' (beginning), or `SEEK_END' (end of file). If ORIGIN is
  430.      omitted, `SEEK_SET' is assumed.  The offset must be zero, or a
  431.      value returned by `ftell' (in which case ORIGIN must be `SEEK_SET'.
  432.  - Built-in Variable: SEEK_SET
  433.  - Built-in Variable: SEEK_CUR
  434.  - Built-in Variable: SEEK_END
  435.      These variables may be used as the optional third argument for the
  436.      function `fseek'.
  437.  - Built-in Function:  frewind (FID)
  438.      Move the file pointer to the beginning of the file FID, returning
  439.      1 for success, and 0 if an error was encountered.  It is
  440.      equivalent to `fseek (FID, 0, SEEK_SET)'.
  441.    The following example stores the current file position in the
  442. variable `marker', moves the pointer to the beginning of the file, reads
  443. four characters, and then returns to the original position.
  444.      marker = ftell (myfile);
  445.      frewind (myfile);
  446.      fourch = fgets (myfile, 4);
  447.      fseek (myfile, marker, SEEK_SET);
  448. File: octave,  Node: Plotting,  Next: Matrix Manipulation,  Prev: Input and Output,  Up: Top
  449. Plotting
  450. ********
  451.    All of Octave's plotting functions use `gnuplot' to handle the
  452. actual graphics.  There are two low-level functions, `gplot' and
  453. `gsplot', that behave almost exactly like the corresponding `gnuplot'
  454. functions `plot' and `splot'.  A number of other higher level plotting
  455. functions, patterned after the graphics functions found in MATLAB
  456. version 3.5, are also available.  These higher level functions are all
  457. implemented in terms of the two low-level plotting functions.
  458. * Menu:
  459. * Two-Dimensional Plotting::
  460. * Specialized Two-Dimensional Plots::
  461. * Three-Dimensional Plotting::
  462. * Plot Annotations::
  463. * Multiple Plots on One Page::
  464. File: octave,  Node: Two-Dimensional Plotting,  Next: Specialized Two-Dimensional Plots,  Prev: Plotting,  Up: Plotting
  465. Two-Dimensional Plotting
  466. ========================
  467.  - Command: gplot RANGES EXPRESSION USING TITLE STYLE
  468.      Generate a 2-dimensional plot.
  469.      The RANGES, USING, TITLE, and STYLE arguments are optional, and
  470.      the USING, TITLE and STYLE qualifiers may appear in any order
  471.      after the expression.  You may plot multiple expressions with a
  472.      single command by separating them with commas.  Each expression
  473.      may have its own set of qualifiers.
  474.      The optional item RANGES has the syntax
  475.           [ x_lo : x_up ] [ y_lo : y_up ]
  476.      and may be used to specify the ranges for the axes of the plot,
  477.      independent of the actual range of the data.  The range for the y
  478.      axes and any of the individual limits may be omitted.  A range
  479.      `[:]' indicates that the default limits should be used.  This
  480.      normally means that a range just large enough to include all the
  481.      data points will be used.
  482.      The expression to be plotted must not contain any literal matrices
  483.      (e.g. `[ 1, 2; 3, 4 ]') since it is nearly impossible to
  484.      distinguish a plot range from a matrix of data.
  485.      See the help for `gnuplot' for a description of the syntax for the
  486.      optional items.
  487.      By default, the `gplot' command plots the second column of a matrix
  488.      versus the first.  If the matrix only has one column, it is taken
  489.      as a vector of y-coordinates and the x-coordinate is taken as the
  490.      element index, starting with zero.  For example,
  491.           gplot rand (100,1) with linespoints
  492.      will plot 100 random values and connect them with lines.  When
  493.      `gplot' is used to plot a column vector, the indices of the
  494.      elements are taken as x values.
  495.      If there are more than two columns, you can choose which columns
  496.      to plot with the USING qualifier. For example, given the data
  497.           x = (-10:0.1:10)';
  498.           data = [x, sin(x), cos(x)];
  499.      the command
  500.           gplot [-11:11] [-1.1:1.1] \
  501.             data with lines, data using 1:3 with impulses
  502.      will plot two lines.  The first line is generated by the command
  503.      `data with lines', and is a graph of the sine function over the
  504.      range -10 to 10.  The data is taken from the first two columns of
  505.      the matrix because columns to plot were not specified with the
  506.      USING qualifier.
  507.      The clause `using 1:3' in the second part of this plot command
  508.      specifies that the first and third columns of the matrix `data'
  509.      should be taken as the values to plot.
  510.      In this example, the ranges have been explicitly specified to be a
  511.      bit larger than the actual range of the data so that the curves do
  512.      not touch the border of the plot.
  513.  - Command: gset OPTIONS
  514.  - Command: gshow OPTIONS
  515.  - Command: replot OPTIONS
  516.      In addition to the basic plotting commands, the whole range of
  517.      `gset' and `gshow' commands from `gnuplot' are available, as is
  518.      `replot'.
  519.      Note that in Octave 2.0, the `set' and `show' commands were
  520.      renamed to `gset' and `gshow' in order to allow for compatibility
  521.      with the MATLAB graphics and GUI commands in a future version of
  522.      Octave.  (For now, the old `set' and `show' commands do work, but
  523.      they print an annoying warning message to try to get people to
  524.      switch to using `gset' and `gshow'.)
  525.      The `gset' and `gshow' commands allow you to set and show
  526.      `gnuplot' parameters.  For more information about the `gset' and
  527.      `gshow' commands, see the documentation for `set' and `show' in
  528.      the `gnuplot' user's guide (also available on line if you run
  529.      `gnuplot' directly, instead of running it from Octave).
  530.      The `replot' command allows you to force the plot to be
  531.      redisplayed.  This is useful if you have changed something about
  532.      the plot, such as the title or axis labels.  The `replot' command
  533.      also accepts the same arguments as `gplot' or `gsplot' (except for
  534.      data ranges) so you can add additional lines to existing plots.
  535.      For example,
  536.           gset term tek40
  537.           gset output "/dev/plotter"
  538.           gset title "sine with lines and cosine with impulses"
  539.           replot "sin (x) w l"
  540.      will change the terminal type for plotting, add a title to the
  541.      current plot, add a graph of sin (x) to the plot, and force the
  542.      new plot to be sent to the plot device.  This last step is
  543.      normally required in order to update the plot.  This default is
  544.      reasonable for slow terminals or hardcopy output devices because
  545.      even when you are adding additional lines with a replot command,
  546.      gnuplot always redraws the entire plot, and you probably don't
  547.      want to have a completely new plot generated every time something
  548.      as minor as an axis label changes.
  549.      The command `shg' is equivalent to executing `replot' without any
  550.      arguments.
  551.  - Built-in Variable: automatic_replot
  552.      You can tell Octave to redisplay the plot each time anything about
  553.      it changes by setting the value of the builtin variable
  554.      `automatic_replot' to a nonzero value.  Since this is fairly
  555.      inefficient, the default value is 0.
  556.    Note that NaN values in the plot data are automatically omitted, and
  557. Inf values are converted to a very large value before calling gnuplot.
  558.    The MATLAB-style two-dimensional plotting commands are:
  559.  - Function File:  plot (ARGS)
  560.      This function produces two-dimensional plots.  Many different
  561.      combinations of arguments are possible.  The simplest form is
  562.           plot (Y)
  563.      where the argument is taken as the set of Y coordinates and the X
  564.      coordinates are taken to be the indices of the elements, starting
  565.      with 1.
  566.      If more than one argument is given, they are interpreted as
  567.           plot (X, Y, FMT ...)
  568.      where Y and FMT are optional, and any number of argument sets may
  569.      appear.  The X and Y values are interpreted as follows:
  570.         * If a single data argument is supplied, it is taken as the set
  571.           of Y coordinates and the X coordinates are taken to be the
  572.           indices of the elements, starting with 1.
  573.         * If the first argument is a vector and the second is a matrix,
  574.           the the vector is plotted versus the columns (or rows) of the
  575.           matrix.  (using whichever combination matches, with columns
  576.           tried first.)
  577.         * If the first argument is a matrix and the second is a vector,
  578.           the the columns (or rows) of the matrix are plotted versus
  579.           the vector.  (using whichever combination matches, with
  580.           columns tried first.)
  581.         * If both arguments are vectors, the elements of Y are plotted
  582.           versus the elements of X.
  583.         * If both arguments are matrices, the columns of Y are plotted
  584.           versus the columns of X.  In this case, both matrices must
  585.           have the same number of rows and columns and no attempt is
  586.           made to transpose the arguments to make the number of rows
  587.           match.
  588.           If both arguments are scalars, a single point is plotted.
  589.      The FMT argument, if present is interpreted as follows.  If FMT is
  590.      missing, the default gnuplot line style is assumed.
  591.     `-'
  592.           Set lines plot style (default).
  593.     `.'
  594.           Set dots plot style.
  595.     `@'
  596.           Set points plot style.
  597.     `-@'
  598.           Set linespoints plot style.
  599.     `^'
  600.           Set impulses plot style.
  601.     `L'
  602.           Set steps plot style.
  603.     `#'
  604.           Set boxes plot style.
  605.     `~'
  606.           Set errorbars plot style.
  607.     `#~'
  608.           Set boxerrorbars plot style.
  609.     `N'
  610.           Interpreted as the plot color if N is an integer in the range
  611.           1 to 6.
  612.     `NM'
  613.           If NM is a two digit integer and M is an integer in the range
  614.           1 to 6, M is interpreted as the point style.  This is only
  615.           valid in combination with the `@' or `-@' specifiers.
  616.     `C'
  617.           If C is one of `"r"', `"g"', `"b"', `"m"', `"c"', or `"w"',
  618.           it is interpreted as the plot color (red, green, blue,
  619.           magenta, cyan, or white).
  620.     `+'
  621.     `*'
  622.     `o'
  623.     `x'
  624.           Used in combination with the points or linespoints styles,
  625.           set the point style.
  626.      The color line styles have the following meanings on terminals that
  627.      support color.
  628.           Number  Gnuplot colors  (lines)points style
  629.             1       red                   *
  630.             2       green                 +
  631.             3       blue                  o
  632.             4       magenta               x
  633.             5       cyan                house
  634.             6       brown            there exists
  635.      Here are some plot examples:
  636.           plot (x, y, "@12", x, y2, x, y3, "4", x, y4, "+")
  637.      This command will plot `y' with points of type 2 (displayed as
  638.      `+') and color 1 (red), `y2' with lines, `y3' with lines of color
  639.      4 (magenta) and `y4' with points displayed as `+'.
  640.           plot (b, "*")
  641.      This command will plot the data in the variable `b' will be plotted
  642.      with points displayed as `*'.
  643.  - Function File:  hold ARGS
  644.      Tell Octave to `hold' the current data on the plot when executing
  645.      subsequent plotting commands.  This allows you to execute a series
  646.      of plot commands and have all the lines end up on the same figure.
  647.      The default is for each new plot command to clear the plot device
  648.      first.  For example, the command
  649.           hold on
  650.      turns the hold state on.  An argument of `off' turns the hold state
  651.      off, and `hold' with no arguments toggles the current hold state.
  652.  - Function File:  ishold
  653.      Return 1 if the next line will be added to the current plot, or 0
  654.      if the plot device will be cleared before drawing the next line.
  655.  - Function File:  clearplot
  656.  - Function File:  clg
  657.      Clear the plot window and any titles or axis labels.  The name
  658.      `clg' is aliased to `clearplot' for compatibility with MATLAB.
  659.      The commands `gplot clear', `gsplot clear', and `replot clear' are
  660.      equivalent to `clearplot'.  (Previously, commands like `gplot
  661.      clear' would evaluate `clear' as an ordinary expression and clear
  662.      all the visible variables.)
  663.  - Function File:  closeplot
  664.      Close stream to the `gnuplot' subprocess.  If you are using X11,
  665.      this will close the plot window.
  666.  - Function File:  purge_tmp_files
  667.      Delete the temporary files created by the plotting commands.
  668.      Octave creates temporary data files for `gnuplot' and then sends
  669.      commands to `gnuplot' through a pipe.  Octave will delete the
  670.      temporary files on exit, but if you are doing a lot of plotting
  671.      you may want to clean up in the middle of a session.
  672.      A future version of Octave will eliminate the need to use temporary
  673.      files to hold the plot data.
  674.  - Function File:  axis (LIMITS)
  675.      Sets the axis limits for plots.
  676.      The argument LIMITS should be a 2, 4, or 6 element vector.  The
  677.      first and second elements specify the lower and upper limits for
  678.      the x axis.  The third and fourth specify the limits for the y
  679.      axis, and the fifth and sixth specify the limits for the z axis.
  680.      With no arguments, `axis' turns autoscaling on.
  681.      If your plot is already drawn, then you need to use `replot' before
  682.      the new axis limits will take effect.  You can get this to happen
  683.      automatically by setting the built-in variable `automatic_replot'
  684.      to a nonzero value.
  685. File: octave,  Node: Specialized Two-Dimensional Plots,  Next: Three-Dimensional Plotting,  Prev: Two-Dimensional Plotting,  Up: Plotting
  686. Specialized Two-Dimensional Plots
  687. =================================
  688.  - Function File:  bar (X, Y)
  689.      Given two vectors of x-y data, `bar' produces a bar graph.
  690.      If only one argument is given, it is taken as a vector of y-values
  691.      and the x coordinates are taken to be the indices of the elements.
  692.      If two output arguments are specified, the data are generated but
  693.      not plotted.  For example,
  694.           bar (x, y);
  695.      and
  696.           [xb, yb] = bar (x, y);
  697.           plot (xb, yb);
  698.      are equivalent.
  699.  - Function File:  contour (Z, N, X, Y)
  700.      Make a contour plot of the three-dimensional surface described by
  701.      Z.  Someone needs to improve `gnuplot''s contour routines before
  702.      this will be very useful.
  703.  - Function File:  hist (Y, X)
  704.      Produce histogram counts or plots.
  705.      With one vector input argument, plot a histogram of the values with
  706.      10 bins.  The range of the histogram bins is determined by the
  707.      range of the data.
  708.      Given a second scalar argument, use that as the number of bins.
  709.      Given a second vector argument, use that as the centers of the
  710.      bins, with the width of the bins determined from the adjacent
  711.      values in the vector.
  712.      Extreme values are lumped in the first and last bins.
  713.      With two output arguments, produce the values NN and XX such that
  714.      `bar (XX, NN)' will plot the histogram.
  715.  - Function File:  loglog (ARGS)
  716.      Make a two-dimensional plot using log scales for both axes.  See
  717.      the description of `plot' above for a description of the arguments
  718.      that `loglog' will accept.
  719.  - Function File:  polar (THETA, RHO)
  720.      Make a two-dimensional plot given polar the coordinates THETA and
  721.      RHO.
  722.  - Function File:  semilogx (ARGS)
  723.      Make a two-dimensional plot using a log scale for the X axis.  See
  724.      the description of `plot' above for a description of the arguments
  725.      that `semilogx' will accept.
  726.  - Function File:  semilogy (ARGS)
  727.      Make a two-dimensional plot using a log scale for the Y axis.  See
  728.      the description of `plot' above for a description of the arguments
  729.      that `semilogy' will accept.
  730.  - Function File:  stairs (X, Y)
  731.      Given two vectors of x-y data, bar produces a `stairstep' plot.
  732.      If only one argument is given, it is taken as a vector of y-values
  733.      and the x coordinates are taken to be the indices of the elements.
  734.      If two output arguments are specified, the data are generated but
  735.      not plotted.  For example,
  736.           stairs (x, y);
  737.      and
  738.           [xs, ys] = stairs (x, y);
  739.           plot (xs, ys);
  740.      are equivalent.
  741. File: octave,  Node: Three-Dimensional Plotting,  Next: Plot Annotations,  Prev: Specialized Two-Dimensional Plots,  Up: Plotting
  742. Three-Dimensional Plotting
  743. ==========================
  744.  - Command: gsplot RANGES EXPRESSION USING TITLE STYLE
  745.      Generate a 3-dimensional plot.
  746.      The RANGES, USING, TITLE, and STYLE arguments are optional, and
  747.      the USING, TITLE and STYLE qualifiers may appear in any order
  748.      after the expression.  You may plot multiple expressions with a
  749.      single command by separating them with commas.  Each expression
  750.      may have its own set of qualifiers.
  751.      The optional item RANGES has the syntax
  752.           [ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ]
  753.      and may be used to specify the ranges for the axes of the plot,
  754.      independent of the actual range of the data.  The range for the y
  755.      and z axes and any of the individual limits may be omitted.  A
  756.      range `[:]' indicates that the default limits should be used.  This
  757.      normally means that a range just large enough to include all the
  758.      data points will be used.
  759.      The expression to be plotted must not contain any literal matrices
  760.      (e.g.  `[ 1, 2; 3, 4 ]') since it is nearly impossible to
  761.      distinguish a plot range from a matrix of data.
  762.      See the help for `gnuplot' for a description of the syntax for the
  763.      optional items.
  764.      By default, the `gsplot' command plots each column of the
  765.      expression as the z value, using the row index as the x value, and
  766.      the column index as the y value.  The indices are counted from
  767.      zero, not one.  For example,
  768.           gsplot rand (5, 2)
  769.      will plot a random surface, with the x and y values taken from the
  770.      row and column indices of the matrix.
  771.      If parametric plotting mode is set (using the command `gset
  772.      parametric', then `gsplot' takes the columns of the matrix three
  773.      at a time as the x, y and z values that define a line in three
  774.      space.  Any extra columns are ignored, and the x and y values are
  775.      expected to be sorted.  For example, with `parametric' set, it
  776.      makes sense to plot a matrix like
  777.           1 1 3 2 1 6 3 1 9
  778.           1 2 2 2 2 5 3 2 8
  779.           1 3 1 2 3 4 3 3 7
  780.      but not `rand (5, 30)'.
  781.    The MATLAB-style three-dimensional plotting commands are:
  782.  - Function File:  mesh (X, Y, Z)
  783.      Plot a mesh given matrices `x', and Y from `meshdom' and a matrix
  784.      Z corresponding to the X and Y coordinates of the mesh.
  785.  - Function File:  meshdom (X, Y)
  786.      Given vectors of X and Y coordinates, return two matrices
  787.      corresponding to the X and Y coordinates of the mesh.
  788.      See the file `sombrero.m' for an example of using `mesh' and
  789.      `meshdom'.
  790.  - Built-in Variable: gnuplot_binary
  791.      The name of the program invoked by the plot command.  The default
  792.      value is `"gnuplot"'.  *Note Installation::.
  793.  - Built-in Variable: gnuplot_has_frames
  794.      If the value of this variable is nonzero, Octave assumes that your
  795.      copy of gnuplot has support for multiple frames that is included
  796.      in recent 3.6beta releases.  It's initial value is determined by
  797.      configure, but it can be changed in your startup script or at the
  798.      command line in case configure got it wrong, or if you upgrade
  799.      your gnuplot installation.
  800.  - Function File:  figure (N)
  801.      Set the current plot window to plot window N.  This function
  802.      currently requires X11 and a version of gnuplot that supports
  803.      multiple frames.
  804.  - Built-in Variable: gnuplot_has_multiplot
  805.      If the value of this variable is nonzero, Octave assumes that your
  806.      copy of gnuplot has the multiplot support that is included in
  807.      recent 3.6beta releases.  It's initial value is determined by
  808.      configure, but it can be changed in your startup script or at the
  809.      command line in case configure got it wrong, or if you upgrade
  810.      your gnuplot installation.
  811. File: octave,  Node: Plot Annotations,  Next: Multiple Plots on One Page,  Prev: Three-Dimensional Plotting,  Up: Plotting
  812. Plot Annotations
  813. ================
  814.  - Function File:  grid
  815.      For two-dimensional plotting, force the display of a grid on the
  816.      plot.
  817.  - Function File:  title (STRING)
  818.      Specify a title for the plot.  If you already have a plot
  819.      displayed, use the command `replot' to redisplay it with the new
  820.      title.
  821.  - Function File:  xlabel (STRING)
  822.  - Function File:  ylabel (STRING)
  823.  - Function File:  zlabel (STRING)
  824.      Specify x, y, and z axis labels for the plot.  If you already have
  825.      a plot displayed, use the command `replot' to redisplay it with
  826.      the new labels.
  827. File: octave,  Node: Multiple Plots on One Page,  Prev: Plot Annotations,  Up: Plotting
  828. Multiple Plots on One Page
  829. ==========================
  830.    The following functions all require a version of `gnuplot' that
  831. supports the multiplot feature.
  832.  - Function File:  mplot (X, Y)
  833.  - Function File:  mplot (X, Y, FMT)
  834.  - Function File:  mplot (X1, Y1, X2, Y2)
  835.      This is a modified version of the `plot' function that works with
  836.      the multiplot version of `gnuplot' to plot multiple plots per page.
  837.      This plot version automatically advances to the next subplot
  838.      position after each set of arguments are processed.
  839.      See the description of the PLOT function for the various options.
  840.  - Function File:  multiplot (XN, YN)
  841.      Sets and resets multiplot mode.
  842.      If the arguments are non-zero, `multiplot' will set up multiplot
  843.      mode with XN, YN subplots along the X and Y axes.  If both
  844.      arguments are zero, `multiplot' closes multiplot mode.
  845.  - Function File:  oneplot ()
  846.      If in multiplot mode, switches to single plot mode.
  847.  - Function File:  plot_border (...)
  848.      Multiple arguments allowed to specify the sides on which the border
  849.      is shown.  Allowed arguments include:
  850.     `"blank"'
  851.           No borders displayed.
  852.     `"all"'
  853.           All borders displayed
  854.     `"north"'
  855.           North Border
  856.     `"south"'
  857.           South Border
  858.     `"east"'
  859.           East Border
  860.     `"west"'
  861.           West Border
  862.      The arguments may be abbreviated to single characters.  Without any
  863.      arguments, `plot_border' turns borders off.
  864.  - Function File:  subplot (ROWS, COLS, INDEX)
  865.  - Function File:  subplot (RCN)
  866.      Sets `gnuplot' in multiplot mode and plots in location given by
  867.      index (there are COLS by ROWS subwindows).
  868.      Input:
  869.     ROWS
  870.           Number of rows in subplot grid.
  871.     COLUMNS
  872.           Number of columns in subplot grid.
  873.     INDEX
  874.           Index of subplot where to make the next plot.
  875.      If only one argument is supplied, then it must be a three digit
  876.      value specifying the location in digits 1 (rows) and 2 (columns)
  877.      and the plot index in digit 3.
  878.      The plot index runs row-wise.  First all the columns in a row are
  879.      filled and then the next row is filled.
  880.      For example, a plot with 4 by 2 grid will have plot indices
  881.      running as follows:
  882.           +-----+-----+-----+-----+
  883.           |  1  |  2  |  3  |  4  |
  884.           +-----+-----+-----+-----+
  885.           |  5  |  6  |  7  |  8  |
  886.           +-----+-----+-----+-----+
  887.  - Function File:  subwindow (XN, YN)
  888.      Sets the subwindow position in multiplot mode for the next plot.
  889.      The multiplot mode has to be previously initialized using the
  890.      `multiplot' function, otherwise this command just becomes an alias
  891.      to `multiplot'
  892.  - Function File:  top_title (STRING)
  893.  - Function File:  bottom_title (STRING)
  894.      Makes a title with text STRING at the top (bottom) of the plot.
  895. File: octave,  Node: Matrix Manipulation,  Next: Arithmetic,  Prev: Plotting,  Up: Top
  896. Matrix Manipulation
  897. *******************
  898.    There are a number of functions available for checking to see if the
  899. elements of a matrix meet some condition, and for rearranging the
  900. elements of a matrix.  For example, Octave can easily tell you if all
  901. the elements of a matrix are finite, or are less than some specified
  902. value.  Octave can also rotate the elements, extract the upper- or
  903. lower-triangular parts, or sort the columns of a matrix.
  904. * Menu:
  905. * Finding Elements and Checking Conditions::
  906. * Rearranging Matrices::
  907. * Special Utility Matrices::
  908. * Famous Matrices::
  909. File: octave,  Node: Finding Elements and Checking Conditions,  Next: Rearranging Matrices,  Prev: Matrix Manipulation,  Up: Matrix Manipulation
  910. Finding Elements and Checking Conditions
  911. ========================================
  912.    The functions `any' and `all' are useful for determining whether any
  913. or all of the elements of a matrix satisfy some condition.  The `find'
  914. function is also useful in determining which elements of a matrix meet
  915. a specified condition.
  916.  - Built-in Function:  any (X)
  917.      For a vector argument, return 1 if any element of the vector is
  918.      nonzero.
  919.      For a matrix argument, return a row vector of ones and zeros with
  920.      each element indicating whether any of the elements of the
  921.      corresponding column of the matrix are nonzero.  For example,
  922.           any (eye (2, 4))
  923.                => [ 1, 1, 0, 0 ]
  924.      To see if any of the elements of a matrix are nonzero, you can use
  925.      a statement like
  926.           any (any (a))
  927.  - Built-in Function:  all (X)
  928.      The function `all' behaves like the function `any', except that it
  929.      returns true only if all the elements of a vector, or all the
  930.      elements in a column of a matrix, are nonzero.
  931.    Since the comparison operators (*note Comparison Ops::.) return
  932. matrices of ones and zeros, it is easy to test a matrix for many
  933. things, not just whether the elements are nonzero.  For example,
  934.      all (all (rand (5) < 0.9))
  935.           => 0
  936. tests a random 5 by 5 matrix to see if all of it's elements are less
  937. than 0.9.
  938.    Note that in conditional contexts (like the test clause of `if' and
  939. `while' statements) Octave treats the test as if you had typed `all
  940. (all (condition))'.
  941.  - Function File: [ERR, Y1, ...] = common_size (X1, ...)
  942.      Determine if all input arguments are either scalar or of common
  943.      size.  If so, ERR is zero, and YI is a matrix of the common size
  944.      with all entries equal to XI if this is a scalar or XI otherwise.
  945.      If the inputs cannot be brought to a common size, errorcode is 1,
  946.      and YI is XI.  For example,
  947.           [errorcode, a, b] = common_size ([1 2; 3 4], 5)
  948.                => errorcode = 0
  949.                => a = [ 1, 2; 3, 4 ]
  950.                => b = [ 5, 5; 5, 5 ]
  951.      This is useful for implementing functions where arguments can
  952.      either be scalars or of common size.
  953.  - Function File:  diff (X, K)
  954.      If X is a vector of length N, `diff (X)' is the vector of first
  955.      differences  X(2) - X(1), ..., X(n) - X(n-1).
  956.      If X is a matrix, `diff (X)' is the matrix of column differences.
  957.      The second argument is optional.  If supplied, `diff (X, K)',
  958.      where K is a nonnegative integer, returns the K-th differences.
  959.  - Mapping Function:  isinf (X)
  960.      Return 1 for elements of X that are infinite and zero otherwise.
  961.      For example,
  962.           isinf ([13, Inf, NaN])
  963.                => [ 0, 1, 0 ]
  964.  - Mapping Function:  isnan (X)
  965.      Return 1 for elements of X that are NaN values and zero otherwise.
  966.      For example,
  967.           isnan ([13, Inf, NaN])
  968.                => [ 0, 0, 1 ]
  969.  - Mapping Function:  finite (X)
  970.      Return 1 for elements of X that are NaN values and zero otherwise.
  971.      For example,
  972.           finite ([13, Inf, NaN])
  973.                => [ 1, 0, 0 ]
  974.  - Loadable Function:  find (X)
  975.      Return a vector of indices of nonzero elements of a matrix.  To
  976.      obtain a single index for each matrix element, Octave pretends
  977.      that the columns of a matrix form one long vector (like Fortran
  978.      arrays are stored).  For example,
  979.           find (eye (2))
  980.                => [ 1; 4 ]
  981.      If two outputs are requested, `find' returns the row and column
  982.      indices of nonzero elements of a matrix.  For example,
  983.           [i, j] = find (2 * eye (2))
  984.                => i = [ 1; 2 ]
  985.                => j = [ 1; 2 ]
  986.      If three outputs are requested, `find' also returns a vector
  987.      containing the the nonzero values.  For example,
  988.           [i, j, v] = find (3 * eye (2))
  989.                => i = [ 1; 2 ]
  990.                => j = [ 1; 2 ]
  991.                => v = [ 3; 3 ]
  992.